<html>
<head>
<title>GeoJSON</title>
</head>

<body bgcolor="#ffffff">

<h1>GeoJSON</h1>

<p>This driver implements read/write support for access to features encoded in  
<a href="http://geojson.org/">GeoJSON</a> format. The GeoJSON is a dialect based on the 
<a href="http://json.org/">JavaScript Object Notation (JSON)</a>. The JSON is a lightweight 
plain text format for data interchange and GeoJSON is nothing other than its specialization for geographic content.</p>

<p>At the moment of writing this, GeoJSON is supported as output format of services implemented by 
<a href="http://featureserver.org/">FeatureServer</a>, <a href="http://docs.codehaus.org/display/GEOSDOC/GeoJSON+Output+Format">GeoServer</a> 
and <a href="http://exportgge.sourceforge.net/kml/">CartoWeb</a>.</p>

<p>The OGR GeoJSON driver translates a GeoJSON encoded data to objects of <a href="/ogr/ogr_arch.html">OGR Simple Features model</a>: 
Datasource, Layer, Feature, Geometry. 
The implementation is based on <a href="http://wiki.geojson.org/GeoJSON_draft_version_5">GeoJSON Specification draft, v5.0</a>.</p>

<p>Starting with OGR 1.8.0, the GeoJSON driver can read the JSON output of Feature Service request following the
<a href="http://www.esri.com/industries/landing-pages/geoservices/geoservices.html">GeoServices REST Specification<a/>, like
implemented by <a href="http://help.arcgis.com/en/arcgisserver/10.0/apis/rest/index.html">ArcGIS Server REST API</a></p>

<h2>Datasource</h2>

<p>The OGR GeoJSON driver accepts three types of sources of data:
<ul>
    <li>Uniform Resource Locator (<a href="http://en.wikipedia.org/wiki/URL">URL</a>) - a Web address to 
    perform <a href="http://en.wikipedia.org/wiki/HTTP">HTTP</a> request</li>
<li>Plain text file with GeoJSON data - identified from the file extension .geojson or .json</li>
<li>Text passed directly and encoded in GeoJSON</li>
</ul>
<h2>Layer</h2>

<p>A GeoJSON datasource is translated to single OGRLayer object with pre-defined name <em>OGRGeoJSON</em>:
<pre>
ogrinfo -ro http://featureserver/data/.geojson OGRGeoJSON
</pre>
It's also valid to assume that OGRDataSource::GetLayerCount() for GeoJSON datasource always returns 1.
</p>

<p>Accessing Web Service as a datasource (ie. FeatureServer), each request will produce new layer.
This behavior conforms to stateless nature of HTTP transaction and is similar to how Web browsers operate:
single request == single page.</p>

<p>If a top-level member of GeoJSON data is of any other type than <em>FeatureCollection</em>, the driver will
produce a layer with only one feature. Otherwise, a layer will consists of a set of features.</p>

<h2>Feature</h2>

<p>The OGR GeoJSON driver maps each object of following types to new <em>OGRFeature</em> object:
Point, LineString, Polygon, GeometryCollection, Feature.</p>

<p>According to the <em>GeoJSON Specification</em>, only the <em>Feature</em> object must have a member with 
name <em>properties</em>. Each and every member of <em>properties</em> is translated to OGR object of type of 
OGRField and added to corresponding OGRFeature object.</p>

<p>The <em>GeoJSON Specification</em> does not require all <em>Feature</em> objects in a collection must 
have the same schema of properties. If <em>Feature</em> objects in a set defined by <em>FeatureCollection</em> 
object have different schema of properties, then resulting schema of fields in OGRFeatureDefn is generated as 
<a href="http://en.wikipedia.org/wiki/Union_(set_theory)">union</a> of all <em>Feature</em> properties.</p>

<p>It is possible to tell the driver to not to process attributes by setting environment variable 
<strong>ATTRIBUTES_SKIP=YES</strong>. Default behavior is to preserve all attributes (as an union, see previous paragraph), 
what is equal to setting <strong>ATTRIBUTES_SKIP=NO</strong>.</p>

<h2>Geometry</h2>

<p>Similarly to the issue with mixed-properties features, the <em>GeoJSON Specification</em> draft does not require 
all <em>Feature</em> objects in a collection must have geometry of the same type. Fortunately, OGR objects model does 
allow to have geometries of different types in single layer - a heterogeneous layer. By default, the GeoJSON driver 
preserves type of geometries.</p>

<p>However, sometimes there is a need to generate homogeneous layer from a set of heterogeneous features. 
For this purpose, it's possible to tell the driver to wrap all geometries with OGRGeometryCollection type as a common denominator.
This behavior may be controlled by setting environment variable <strong>GEOMETRY_AS_COLLECTION=YES</strong> (default is <strong>NO</strong>).</p>

<h2>Environment variables</h2>

<ul>
<li><b>GEOMETRY_AS_COLLECTION</b> - used to control translation of geometries: YES - wrap geometries with OGRGeometryCollection type</li>
<li><b>ATTRIBUTES_SKIP</b> - controls translation of attributes: YES - skip all attributes</li>
</ul>

<h2>Layer creation option</h2>

<ul>
<li><b>WRITE_BBOX</b> = YES/NO : (OGR >= 1.9.0) Set to YES to write a bbox property with the bounding box of the geometries at the feature and feature
collection level. Defaults to NO.</li>
<li><b>COORDINATE_PRECISION</b> = int_number : (OGR >= 1.9.0) Maximum number of figures after decimal separator to write in coordinates.
Default to 15. "Smart" truncation will occur to remove trailing zeros.</li>
</ul>

<h2>VSI Virtual File System API support</h2>

(Some features below might require OGR >= 1.9.0)<p>

The driver supports reading and writing to files managed by VSI Virtual File System API, which include
"regular" files, as well as files in the /vsizip/ (read-write) , /vsigzip/ (read-write) , /vsicurl/ (read-only) domains.<p>

Writing to /dev/stdout or /vsistdout/ is also supported.<p>

<h2>Example</h2>

<p>How to dump content of .geojson file:
<pre>
ogrinfo -ro point.geojson
</pre>
</p>

<p>How to query features from remote service with filtering by attribute:
<pre>
ogrinfo -ro http://featureserver/cities/.geojson OGRGeoJSON -where "name=Warsaw"
</pre>
</p>

<p>How to translate number of features queried from FeatureServer to ESRI Shapefile:
<pre>
ogr2ogr -f "ESRI Shapefile" cities.shp http://featureserver/cities/.geojson OGRGeoJSON
</pre>
</p>

<p>Read the result of a FeatureService request against a GeoServices REST server:
<pre>
ogrinfo -ro -al "http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Hydrography/Watershed173811/FeatureServer/0/query?where=objectid+%3D+objectid&amp;outfields=*&amp;f=json"
</pre>
</p>

<h2>See Also</h2>

<p>
<ul>
<li><a href="http://geojson.org/">GeoJSON</a> - encoding geographic content in JSON</li>
<li><a href="http://json.org/">JSON</a> - JavaScript Object Notation</li>
<li><a href="http://oss.metaparadigm.com/json-c/">JSON-C</a> - A JSON implementation in C</li>
<li><a href="http://lists.osgeo.org/pipermail/gdal-dev/2007-November/014746.html">[Gdal-dev] OGR GeoJSON Driver</a> - driver announcement</li>
<li><a href="http://www.esri.com/industries/landing-pages/geoservices/geoservices.html">GeoServices REST Specification<a/></li>
</ul>
</p>

</body>
</html>

